Skip to main content

Regex JQL Function

This document describes the regex JQL function that allows you to search for issues using regular expressions to match field values.

Overview​

The regex JQL function enables you to perform pattern matching on field values using regular expressions. This is particularly useful when you need to find issues based on complex text patterns in fields like summary, description, or custom text fields.

Available Function​

regex(jql, field, pattern)​

Finds issues where the specified field's value matches the given regular expression pattern.

Example:

issue in regex("project = SER", "summary", "bug.*critical")

This query finds all issues in the SER project where the summary field contains the word "bug" followed by "critical" (with any characters in between).

Usage Notes​

  1. The function requires three arguments:
    • A valid JQL subquery
    • The name of the field to search in
    • A valid regular expression pattern
  2. The function supports the following operators: "in", "not in"
  3. Results are calculated based on the current values of the fields at the time of the query.

Syntax​

The general syntax for using the regex function in JQL is:

issue [operator] regex("jql_subquery", "field_name", "pattern")

Where:

  • operator is either "in" or "not in"
  • jql_subquery is a valid JQL query that returns a set of issues
  • field_name is the name of the field to search in
  • pattern is a valid regular expression pattern

Field Types and Format Support​

Field Types​

The regex function works with various field types:

  • Text fields (Summary, Description)
  • Custom text fields
  • Status fields
  • Priority fields
  • Labels
  • Issue types
  • And other text-based fields

Custom Fields​

When using custom fields:

  • Always use the field's display name, not its ID
  • Example: Use "Story Points" instead of "customfield_10001"

Atlassian Document Format (ADF)​

The function automatically handles fields that use Atlassian Document Format (ADF):

  • Description field
  • Custom fields using ADF
  • The function will automatically extract plain text from ADF content for pattern matching

Regular Expression Support​

Supported Syntax​

The function supports standard regular expression syntax with some JQL-specific limitations:

  1. Character Classes:

    • Use [0-9] instead of \d for digits
    • Use [.] instead of \. for literal dots
    • Other character classes like [a-z], [A-Z], [^abc] work as expected

  2. Quantifiers:

    • * (zero or more)
    • + (one or more)
    • ? (zero or one)
    • {n} (exactly n times)
    • {n,} (n or more times)
    • {n,m} (between n and m times)

  3. Anchors:

    • ^ (start of string)
    • $ (end of string)

  4. Groups and Alternation:

    • (...) for grouping
    • | for alternation

JQL Limitations​

JQL has limited escape sequence support. The only valid escape sequences are:

  • \\' (single quote)
  • \\" (double quote)
  • \\t (tab)
  • \\n (newline)
  • \\r (carriage return)
  • \\\\ (backslash)
  • \\ (space)
  • \\uXXXX (Unicode character)

Examples​

Finding issues with version numbers in summary​

# Match version numbers anywhere in the summary
issue in regex("project = SER", "summary", "v[0-9]+[.][0-9]+[.][0-9]+")

# Match only summaries that contain exactly a version number
issue in regex("project = SER", "summary", "^v[0-9]+[.][0-9]+[.][0-9]+$")

The first pattern will match summaries like:

  • "v1.2.3"
  • "v1.2.3 2025-05-21T18:38:36.554Z"
  • "Release v1.2.3 is ready"

The second pattern (with anchors) will only match summaries that contain exactly a version number:

  • "v1.2.3" ✓
  • "v1.2.3 2025-05-21T18:38:36.554Z" ✗
  • "Release v1.2.3 is ready" ✗

Finding issues with email addresses in description​

issue in regex("project = SER", "description", "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+[.][a-zA-Z]{2,}")

Finding issues with specific date format in a custom field​

issue in regex("project = SER", "Approvers", "[0-9]{2}/[0-9]{2}/[0-9]{4}")

Finding issues without numbers in summary​

issue not in regex("project = SER", "summary", "[0-9]")

Finding issues with specific error codes​

issue in regex("project = SER", "description", "ERROR-[A-Z]{2}[0-9]{4}")

Best Practices​

  1. Always provide a valid JQL subquery:

    • The subquery must be a valid JQL expression
    • The subquery should be specific enough to return a manageable set of issues

  2. Use appropriate regular expressions:

    • Keep patterns as specific as possible to avoid false matches
    • Test your regular expressions before using them in production
    • Consider using non-greedy quantifiers when appropriate
    • Use JQL-compatible escape sequences

  3. Consider performance implications:

    • Complex regular expressions may impact query performance
    • Very broad subqueries may slow down the search
    • Consider using more specific subqueries to limit the result set

  4. Combine with other JQL functions:

    • The regex function can be combined with other JQL functions
    • Use parentheses to ensure proper operator precedence

Error Handling​

The function will return an error if:

  1. The regular expression pattern is invalid
  2. The specified field name is not valid
  3. The JQL subquery is invalid
  4. The field name is not found in the system

Performance Considerations​

  1. Regular Expression Complexity:

    • Simple patterns are faster than complex ones
    • Avoid using too many wildcards or complex quantifiers
    • Consider using more specific patterns when possible

  2. Field Size:

    • Searching in large text fields (like description) may be slower
    • Consider using more specific subqueries to limit the result set

  3. Result Set Size:

    • Large result sets may impact performance
    • Use appropriate subqueries to limit the number of issues to search through